{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Getting Started with EdgarTools\n",
    "\n",
    "[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/dgunning/edgartools/blob/main/notebooks/01_getting_started.ipynb)\n",
    "\n",
    "Welcome to **EdgarTools** - a Python library that makes it easy to access and analyze SEC Edgar filings!\n",
    "\n",
    "## What is EdgarTools?\n",
    "\n",
    "EdgarTools is a powerful yet simple library for working with SEC (Securities and Exchange Commission) filings. With just a few lines of code, you can:\n",
    "\n",
    "- \ud83d\udcca Download and parse financial statements\n",
    "- \ud83d\udd0d Search through company filings\n",
    "- \ud83d\udcbc Access company information and facts\n",
    "- \ud83d\udcc8 Extract XBRL financial data\n",
    "- \ud83d\udcc4 Work with 10-K, 10-Q, 8-K, and many other SEC forms\n",
    "\n",
    "## In This Notebook\n",
    "\n",
    "This notebook will walk you through:\n",
    "1. Installing EdgarTools\n",
    "2. Basic setup and configuration\n",
    "3. Your first filing retrieval\n",
    "4. Exploring company information\n",
    "5. Common use cases and examples"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 1. Installation\n",
    "\n",
    "First, let's install EdgarTools. On Google Colab, we can install it directly using pip:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Install edgartools\n",
    "!pip install edgartools -q"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 2. Basic Setup\n",
    "\n",
    "Before using EdgarTools, you should set your identity. The SEC requires that automated tools identify themselves with a user agent string.\n",
    "\n",
    "**Important:** Replace the email below with your actual email address."
   ]
  },
  {
   "cell_type": "code",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2025-12-03T15:58:10.991814Z",
     "start_time": "2025-12-03T15:58:10.988441Z"
    }
   },
   "source": [
    "from edgar import set_identity\n",
    "\n",
    "# Set your identity - use your real email address\n",
    "set_identity(\"Your Name your.email@example.com\")\n",
    "\n",
    "# Alternative: you can also be more specific\n",
    "# set_identity(\"Jane Doe jane.doe@example.com\")"
   ],
   "outputs": [],
   "execution_count": null
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": "## 3. Your First Filing Retrieval\n\nLet's start by finding some filings. There are **two main ways** to get filings in EdgarTools:\n\n1. **`Company().get_filings()`** - When you know the specific company\n2. **`get_filings()`** - When you want to search across all companies in a time period\n\n### Method 1: Company-Specific Filings\n\nUse this when you know the company ticker or name:"
  },
  {
   "cell_type": "code",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2025-12-03T15:58:16.233479Z",
     "start_time": "2025-12-03T15:58:15.652760Z"
    }
   },
   "source": "from edgar import Company\n\n# Get Apple and find its 10-K filings\napple = Company(\"AAPL\")\nfilings = apple.get_filings(form=\"10-K\")\n\n# Display the results\nfilings",
   "outputs": [],
   "execution_count": null
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": "### Understanding the Results\n\nThe result is a `Filings` collection that shows:\n- **Company Name** and **CIK** (Central Index Key)\n- **Form Type** (10-K in this case)\n- **Filing Date**\n- **Accession Number** (unique identifier for each filing)\n\nLet's look at the most recent filing in detail:"
  },
  {
   "cell_type": "code",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2025-12-03T15:58:21.695758Z",
     "start_time": "2025-12-03T15:58:21.607121Z"
    }
   },
   "source": [
    "# Get the most recent filing\n",
    "latest_filing = filings[0]\n",
    "\n",
    "latest_filing"
   ],
   "outputs": [],
   "execution_count": null
  },
  {
   "cell_type": "markdown",
   "source": "### Method 2: Search Across All Companies\n\nUse `get_filings(year, quarter)` when you want to find filings across **all companies** in a specific time period:\n\n**Tip:** This is useful for discovering patterns, screening for events, or analyzing market-wide trends.",
   "metadata": {}
  },
  {
   "cell_type": "code",
   "source": "from edgar import get_filings\n\n# Get all 10-K filings from Q4 2024 (all companies!)\nfilings = get_filings(2024, 4, form=\"10-K\")\n\nprint(f\"Found {len(filings)} 10-K filings in Q4 2024\")\n\n# Filter to just tech companies on NASDAQ\nnasdaq_filings = filings.filter(exchange=\"Nasdaq\")\nprint(f\"NASDAQ 10-Ks: {len(nasdaq_filings)}\")\n\n# Show a few examples\nnasdaq_filings.head(5)",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2025-12-03T15:58:25.947555Z",
     "start_time": "2025-12-03T15:58:24.564980Z"
    }
   },
   "outputs": [],
   "execution_count": null
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 4. Working with Company Objects\n",
    "\n",
    "You can also work directly with a `Company` object to access all information about a company:"
   ]
  },
  {
   "cell_type": "code",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2025-12-03T15:58:29.518880Z",
     "start_time": "2025-12-03T15:58:29.281309Z"
    }
   },
   "source": [
    "from edgar import Company\n",
    "\n",
    "# Get company by ticker\n",
    "apple = Company(\"AAPL\")\n",
    "\n",
    "# Display company information\n",
    "apple"
   ],
   "outputs": [],
   "execution_count": null
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Company Information\n",
    "\n",
    "The Company object provides access to lots of useful information:"
   ]
  },
  {
   "cell_type": "code",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2025-12-03T15:58:33.685550Z",
     "start_time": "2025-12-03T15:58:33.682366Z"
    }
   },
   "source": [
    "# Basic company details\n",
    "print(f\"Name: {apple.name}\")\n",
    "print(f\"CIK: {apple.cik}\")\n",
    "print(f\"SIC: {apple.sic} - {apple.industry}\")\n",
    "print(f\"Fiscal Year End: {apple.fiscal_year_end}\")"
   ],
   "outputs": [],
   "execution_count": null
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Getting Company Filings\n",
    "\n",
    "You can retrieve filings directly from a Company object:"
   ]
  },
  {
   "cell_type": "code",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2025-12-03T15:58:36.337856Z",
     "start_time": "2025-12-03T15:58:36.046403Z"
    }
   },
   "source": [
    "# Get all recent filings\n",
    "all_filings = apple.get_filings()\n",
    "print(f\"Total filings found: {len(all_filings)}\")\n",
    "\n",
    "# Get only 10-Q filings (quarterly reports)\n",
    "quarterly_reports = apple.get_filings(form=\"10-Q\")\n",
    "print(f\"10-Q filings: {len(quarterly_reports)}\")\n",
    "\n",
    "# Display the quarterly reports\n",
    "quarterly_reports.head(5)"
   ],
   "outputs": [],
   "execution_count": null
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 5. Common Use Cases\n",
    "\n",
    "### Use Case 1: Get the Latest Annual Report (10-K)"
   ]
  },
  {
   "cell_type": "code",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2025-12-03T15:58:40.271906Z",
     "start_time": "2025-12-03T15:58:40.200222Z"
    }
   },
   "source": [
    "# Find the most recent 10-K\n",
    "ten_k_filings = apple.get_filings(form=\"10-K\")\n",
    "latest_10k = ten_k_filings[0]\n",
    "\n",
    "print(f\"Latest 10-K for {latest_10k.company}\")\n",
    "print(f\"Filed on: {latest_10k.filing_date}\")\n",
    "print(f\"Reporting period: {latest_10k.period_of_report}\")"
   ],
   "outputs": [],
   "execution_count": null
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Use Case 2: Search Multiple Companies"
   ]
  },
  {
   "cell_type": "code",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2025-12-03T15:58:48.482392Z",
     "start_time": "2025-12-03T15:58:46.837485Z"
    }
   },
   "source": [
    "# Find 8-K filings (current reports) for multiple tech companies\n",
    "companies = [\"AAPL\", \"MSFT\", \"GOOGL\"]\n",
    "\n",
    "for ticker in companies:\n",
    "    filings = Company(ticker).get_filings(form=\"8-K\")\n",
    "    if len(filings) > 0:\n",
    "        print(f\"{ticker}: {len(filings)} 8-K filings found\")\n",
    "        print(f\"  Most recent: {filings[0].filing_date}\")\n",
    "        print()"
   ],
   "outputs": [],
   "execution_count": null
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Use Case 3: Filter Filings by Date Range"
   ]
  },
  {
   "cell_type": "code",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2025-12-03T15:58:59.287559Z",
     "start_time": "2025-12-03T15:58:59.279660Z"
    }
   },
   "source": [
    "# Get filings from a specific date range\n",
    "filings_2023 = apple.get_filings(\n",
    "    form=\"10-Q\",\n",
    "    filing_date=\"2023-01-01:2023-12-31\"\n",
    ")\n",
    "\n",
    "print(f\"10-Q filings in 2023: {len(filings_2023)}\")\n",
    "filings_2023"
   ],
   "outputs": [],
   "execution_count": null
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Use Case 4: Access Filing Documents\n",
    "\n",
    "Each filing contains documents that you can access and parse:"
   ]
  },
  {
   "cell_type": "code",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2025-12-03T15:59:41.461261Z",
     "start_time": "2025-12-03T15:59:41.405513Z"
    }
   },
   "source": [
    "# Get the latest 10-K\n",
    "filing = apple.get_filings(form=\"8-K\")[0]\n",
    "\n",
    "# View the filing homepage (opens in browser)\n",
    "print(f\"Filing homepage: {filing.homepage}\")\n",
    "\n",
    "filing.view()"
   ],
   "outputs": [],
   "execution_count": null
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": "## 6. Next Steps\n\nCongratulations! You've learned the basics of EdgarTools. Here's what you can explore next:\n\n1. **Financial Data** - Learn how to extract XBRL financial statements (see notebook 03_financials.ipynb)\n2. **Document Search** - Search within filing documents for specific information\n3. **Company Facts** - Access pre-computed financial facts from the SEC\n4. **Specific Form Types** - Work with specialized forms like 13F, Form 4, etc.\n\n### Useful Resources\n\n- \ud83d\udcda [EdgarTools Documentation](https://github.com/dgunning/edgartools)\n- \ud83d\udd27 [API Reference](https://github.com/dgunning/edgartools/blob/main/docs)\n- \ud83d\udcac [GitHub Issues](https://github.com/dgunning/edgartools/issues) - Ask questions or report bugs\n\n### Quick Reference\n\n```python\n# Essential imports\nfrom edgar import Company, get_filings, set_identity\n\n# Set your identity (required)\nset_identity(\"Your Name your.email@example.com\")\n\n# Method 1: Get filings for a specific company\ncompany = Company(\"AAPL\")\nfilings = company.get_filings(form=\"10-K\")\n\n# Method 2: Search across all companies in a time period\nall_filings = get_filings(2024, 4, form=\"10-K\")  # Q4 2024\nfiltered = all_filings.filter(exchange=\"Nasdaq\")\n\n# Access a specific filing\nfiling = filings[0]\ndocument = filing.document()\n```"
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Try It Yourself!\n",
    "\n",
    "Use the cell below to experiment with EdgarTools. Try different companies, form types, and date ranges:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Your experiments here\n",
    "# Try different tickers: \"TSLA\", \"NVDA\", \"META\", \"AMZN\"\n",
    "# Try different forms: \"10-K\", \"10-Q\", \"8-K\", \"DEF 14A\"\n"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.10.0"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}